home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 051-075 / scopedisk72 / square / squares.doc < prev    next >
Text File  |  1995-03-19  |  6KB  |  127 lines
  1.                        Documentation for Squares.c  
  2.              Source and Documentation by Michael S. Franzyshen
  3.                                May 8, 1989
  4.  
  5. This simple program takes TWO arguments from the CLI (integer values), and
  6. outputs the specified range of squared values for the numbers.  The two
  7. arguments are the 'Start' and 'End' points of the output range.
  8.  
  9. SYNTAX: Squares <Start> <End>
  10.  
  11. Start is the beginning of the range of squares to output and End is the last
  12. number in the output range. The values for Start and End must fall in the 
  13. range:  -32,768 to +32767. This is the acceptable range for C integer values.
  14. For the correct syntax type:  Squares by itself on the command line. You may 
  15. also terminate the  program by typing Control-C.
  16.  
  17. NOTE:  The function of this program is an example of HOW to pass arguments 
  18. from the CLI to the main() function of your program, not in its utility. When
  19. passing arguments from the CLI to a C main() function, there are several
  20. points that must be kept in mind:
  21.  
  22.   1) The main() definition itself takes ONLY two arguments.
  23.  
  24.   2) One argument is 'argc' which is an integer value specifying the
  25.      number of entries typed at the CLI prompt.  This INCLUDES the 
  26.      program name itself. 
  27.  
  28.                    e.g.  test_program  VAL_1 VAL_2 VAL_3
  29.  
  30.                    In the example above,  argc = 4.
  31.          
  32.                    e.g.  test_program  VAL_1 
  33.       
  34.                    In the example above,  argc = 2.
  35.  
  36.   3) The second argument in the main() function is argv (Argument Vector).
  37.      This is a character array which will hold the arguments entered from
  38.      the CLI.  Using one of the examples from above, suppose we typed from
  39.      the CLI prompt:
  40.  
  41.                       test_program  VAL_1 VAL_2 VAL_3
  42.         
  43.      When the program actually runs, the following assignments are made:
  44.           
  45.                           argv[0] = test_program
  46.                           argv[1] = VAL_1
  47.                           argv[2] = VAL_2
  48.                           argv[3] = VAL_3
  49.  
  50.      NOTE: A common mistake is forgetting that the first element of argv[]
  51.            actually holds the program's name.  
  52.   
  53.   4) Don't  forget that argv is a character array.  If you need to need to
  54.      pass numbers to main(), you must convert the characters to integers,
  55.      floats, or longs (as in this example).  This is done using the C 
  56.      functions atoi() (ASCII to integer), atol() (ASCII to long), or atof()
  57.      (ASCII to float).   
  58.  
  59.   5) As the programmer, you MUST insure the arguments the user types in at
  60.      the CLI, are ones that allow the program to execute properly.  If the
  61.      arguments do not meet the program's criteria, terminate execution, 
  62.      stating WHY the program failed to run.   You will notice in Squares.c
  63.      that a majority of the program is devoted to error checking.
  64.  
  65.      NOTE: Under Manx 3.6a, you must declare the TYPE of value (int,long,
  66.            float, etc), that atol(), atoi(), or atof() are returning, if
  67.            other than an int value.  This is somewhat counter-intuitive for
  68.            beginning C programmers. For example, nowhere is it defined that
  69.            the atol() function is going to return a long int.  If you need 
  70.            the use of a long integer value,  declare it  in the beginning
  71.            of your program the following:
  72.  
  73.                                long     atol();
  74.  
  75.            The same rules apply to atof(), and atoi().
  76.  
  77.   6) Testing for Zero as an argument.  When your program accepts numbers,
  78.      how can you tell if the user types 0 (Zero), or a string of ASCII 
  79.      characters?  The atol() function will return zero in both cases.  For
  80.      example, if the user types:
  81.  
  82.                              Squares  abc  10  
  83.  
  84.      the following result is: atol(argv[1]) = 0.  This is unacceptable, and 
  85.      we want to generate an error.  On the other hand, if the user types:
  86.  
  87.                              Squares  0  10  
  88.  
  89.      In this case atol(argv[1]) = 0 also, but the input is very different.   
  90.      We want to continue program execution, because the VALUE 0 (Zero) is
  91.      acceptable. 
  92.     
  93.      The best way to determine if argv[1] is holding a Zero, or a string of
  94.      random characters, is to test for the ASCII value of Zero (decimal 48)
  95.      pointed to by  *argv[1].  Now if atol(argv[1])  yields Zero, but
  96.      *argv[1] != 48 we know that the  user typed in a string of ASCII
  97.      characters.  If this explanation is not clear, insert printf() in 
  98.      the appropriate sections of code to see the actual values stored by
  99.      *argv[1].  Better yet, if you have SDB from Manx, examine the 
  100.      values of the variables with that.  It is far more dynamic than 
  101.      printf().
  102.      
  103. This program was written using Manx Aztec 3.6a. It was compiled and linked
  104. with these two commands:
  105.    
  106.                                CC Squares.c
  107.                                Ln Squares.o -lc
  108.  
  109. I hope that others can make use of this file, since the conventional 
  110. documentation on this subject is somewhat confusing, and often incomplete. 
  111.  
  112. If you have any questions or comments, please feel free to contact me at the
  113. following:
  114.  
  115.                         COMPUSERVE:     71210,2522
  116.                         GENIE:          xth42864
  117.                         PLINK:          SRU541
  118.  
  119.                           DynaSoft Technologies
  120.                           23 Mercury Street
  121.                           Somerset, NJ  08873
  122.  
  123. The source, executable, and documentation  are public domain, and freely
  124. distributable, as long as this ARC file contains: Squares, Squares.c, and
  125. Squares.doc in its original form.  Feel free to  modify the source to suit
  126. whatever needs you may have while programming your own applications.
  127.